PIC24F
I2C Peripheral Module Library Help
Table Of Contents
2 Using Library Functions in Your Code
3.2 ConfigIntI2C1 , ConfigIntI2C2
3.6 MastergetsI2C1, MastergetsI2C2
3.7 MasterputsI2C1, MasterputsI2C2
3.8 MasterReadI2C1, MasterReadI2C2
3.9 MasterWriteI2C1, MasterWriteI2C2
3.13 SlavegetsI2C1, SlavegetsI2C2
3.14 SlaveputsI2C1, SlaveputsI2C2
3.15 SlaveReadI2C1, SlaveReadI2C2
3.16 SlaveWriteI2C1 , SlaveWriteI2C2
3.19 SlaveWaitForIntrI2C1 , SlaveWaitForIntrI2C2
3.20 MasterWaitForIntrI2C1 , MasterWaitForIntrI2C2
3.21 SlavegetcI2C1 , SlavegetcI2C2
3.22 MastergetcI2C1 , MastergetcI2C2
4.1 EnableIntSI2C1 , EnableIntSI2C2
4.2 DisableIntSI2C1 , DisableIntSI2C2
4.3 EnableIntMI2C1 , EnableIntMI2C2
4.4 DisableIntMI2C1 , DisableIntMI2C2
4.5 SetPriorityIntSI2C1 , SetPriorityIntSI2C2
4.6 SetPriorityIntMI2C1 , SetPriorityIntMI2C2
4.7 mI2C1_MasterClearIntr() , mI2C2_MasterClearIntr()
4.8 mI2C1_SlaveClearIntr () , mI2C2_SlaveClearIntr ()
This peripheral library module:
· Supports BYTE and WORD transmission and reception.
· Incorporates multiple BYTE and WORD transmission and reception in a single function call.
· Provides simple functions to read from and write to the buffers.
· Provides simple interface macros to enable/disable interrupts.
Library routine parameters can be constructed using either AND based mask or AND_OR based mask setting. For more information on these masks, see 16-bit Peripheral Libraries.
Examples of use for both the methods are below.
#include<i2c.h>
void main(void )
{
unsigned int config2, config1;
unsigned char *wrptr;
unsigned char tx_data[] = {'M','I','C','R','O','C','H','I','P','\0'};
wrptr = tx_data;
/* Baud rate is set for 100 Khz */
config2 = 0x11;
/* Configure I2C for 7 bit address mode */
config1 = (I2C_ON & I2C_IDLE_CON & I2C_CLK_HLD &
I2C_IPMI_DIS & I2C_7BIT_ADD &
I2C_SLW_DIS & I2C_SM_DIS &
I2C_GCALL_DIS & I2C_STR_DIS &
I2C_NACK & I2C_ACK_DIS & I2C_RCV_DIS &
I2C_STOP_DIS & I2C_RESTART_DIS &
I2C_START_DIS);
OpenI2C1(config1,config2);
IdleI2C1();
StartI2C1();
/* Wait till Start sequence is completed */
while(I2C1CONbits.SEN );
/* Write Slave address and set master for transmission */
MasterWriteI2C1(0xE);
/* Wait till address is transmitted */
while(I2C1STATbits.TBF);
while(I2C1STATbits.ACKSTAT);
/* Transmit string of data */
MasterputsI2C1(wrptr);
StopI2C1();
/* Wait till stop sequence is completed */
while(I2C1CONbits.PEN);
CloseI2C1();
}
Example of Use ( AND_OR mask )
#define USE_AND_OR /* To enable AND_OR mask setting */
#include<i2c.h>
void main(void )
{
unsigned int config2, config1;
unsigned char *wrptr;
unsigned char tx_data[] = {'M','I','C','R','O','C','H','I','P','\0'};
wrptr = tx_data;
/* Baud rate is set for 100 Khz */
config2 = 0x11;
/* Configure I2C for 7 bit address mode */
config1 = (I2C_ON | I2C_IDLE_CON | I2C_CLK_HLD |
I2C_IPMI_DIS | I2C_7BIT_ADD |
I2C_SLW_DIS | I2C_SM_DIS |
I2C_GCALL_DIS | I2C_STR_DIS |
I2C_NACK | I2C_ACK_DIS | I2C_RCV_DIS |
I2C_STOP_DIS | I2C_RESTART_DIS |
I2C_START_DIS);
OpenI2C1(config1,config2);
IdleI2C1();
StartI2C1();
/* Wait till Start sequence is completed */
while(I2C1CONbits.SEN );
/* Write Slave address and set master for transmission */
MasterWriteI2C1(0xE);
/* Wait till address is transmitted */
while(I2C1STATbits.TBF);
while(I2C1STATbits.ACKSTAT);
/* Transmit string of data */
MasterputsI2C1(wrptr);
StopI2C1();
/* Wait till stop sequence is completed */
while(I2C1CONbits.PEN);
CloseI2C1();
}
Function Prototype |
void CloseI2C1(void); void CloseI2C2(void); |
Include |
i2c.h |
Description |
This function turns off the SPI module. |
Arguments |
None |
Return Value |
None |
Remarks: |
This function disables the I2C module and clears the Master and Slave Interrupt Enable and Flag bits. |
Function Prototype |
ConfigIntI2C1(unsigned int config); ConfigIntI2C2(unsigned int config); |
Include |
i2c.h |
Description |
This function configures the I2C Interrupt. |
Arguments |
config - I2C interrupt priority and enable/disable information as defined below: I2C master Interrupt enable/disable MI2C_INT_ON MI2C_INT_OFF I2C slave Interrupt enable/disable SI2C_INT_ON SI2C_INT_OFF I2C master Interrupt priority MI2C_INT_PRI_7 MI2C_INT_PRI_6 MI2C_INT_PRI_5 MI2C_INT_PRI_4 MI2C_INT_PRI_3 MI2C_INT_PRI_2 MI2C_INT_PRI_1 MI2C_INT_PRI_0 I2C slave Interrupt priority SI2C_INT_PRI_7 SI2C_INT_PRI_6 SI2C_INT_PRI_5 SI2C_INT_PRI_4 SI2C_INT_PRI_3 SI2C_INT_PRI_2 SI2C_INT_PRI_1 SI2C_INT_PRI_0 |
Return Value |
None |
Remarks: |
This function clears the Interrupt Flag bits, sets the interrupt priorities of master and slave and enables/disables the interrupt |
Function Prototype |
void AckI2C1(void); void AckI2C2(void); |
Include |
i2c.h |
Description |
Generates I2C bus Acknowledge condition. |
Arguments |
None |
Return Value |
None |
Remarks: |
This function generates an I2C bus Acknowledge condition. |
Function Prototype |
unsigned char DataRdyI2C1(void); unsigned char DataRdyI2C2(void); |
Include |
i2c.h |
Description |
This function provides status back to user if I2CRCV register contain data. |
Arguments |
None |
Return Value |
This function returns 1 if there is data in I2CRCV register; else return 0 which indicates no data in I2CRCV register. |
Remarks: |
This function determines if there is any byte to read from I2CRCV register. |
Function Prototype |
void IdleI2C1(void); void IdleI2C2(void); |
Include |
i2c.h |
Description |
This function generates Wait condition until I2C bus is Idle. |
Arguments |
None |
Return Value |
None |
Remarks: |
This function will be in a wait state until Start Condition Enable bit, Stop Condition Enable bit, Receive Enable bit, Acknowledge Sequence Enable bit of I2C Control register and Transmit Status bit I2C Status register are clear. The IdleI2C function is required since the hardware I2C peripheral does not allow for spooling of bus sequence. The I2C peripheral must be in Idle state before an I2C operation can be initiated or write collision will be generated. |
Function Prototype |
unsigned int MastergetsI2C1(unsigned int length, unsigned char *rdptr, unsigned int i2c_data_wait); unsigned int MastergetsI2C2(unsigned int length, unsigned char *rdptr, unsigned int i2c_data_wait); |
Include |
i2c.h |
Description |
This function reads predetermined data string length from the I2C bus. |
Arguments |
length - Number of bytes to read from I2C device. rdptr - Character type pointer to RAM for storage of data read from I2C device i2c_data_wait - This is the time-out count for which the module has to wait before return. If the time-out count is N, the actual time out would be about (20 * N 1) instruction cycles. |
Return Value |
This function returns 0 if all bytes have been sent or number of bytes read from I2C bus if its not able to read the data with in the specified i2c_data_wait time out value |
Remarks: |
This routine reads a predefined data string from the I2C bus. |
Function Prototype |
char MasterputsI2C1(unsigned char *wrptr); char MasterputsI2C2(unsigned char *wrptr); |
Include |
i2c.h |
Description |
This function is used to write out a data string to the I2C bus. |
Arguments |
wrptr - Character type pointer to data objects in RAM. The data objects are written to the I2C device. |
Return Value |
This function returns -3 if a write collision occurred. This function returns 0 if the null character was reached in data string. |
Remarks: |
This routine reads a predefined data string from the I2C bus. |
Function Prototype |
char MasterputsI2C1(unsigned char *wrptr); char MasterputsI2C2(unsigned char *wrptr); |
Include |
i2c.h |
Description |
This function is used to read a single byte from I2C bus |
Arguments |
wrptr - Character type pointer to data objects in RAM. The data objects are written to the I2C device. |
Return Value |
The return value is the data byte read from the I2C bus. |
Remarks: |
This function reads in a single byte from the I2C bus. This function performs the same function as MastergetcI2C. |
Function Prototype |
char MasterWriteI2C1(unsigned char data_out); char MasterWriteI2C2(unsigned char data_out); |
Include |
i2c.h |
Description |
This function is used to write out a single data byte to the I2C device. |
Arguments |
data_out - A single data byte to be written to the I2C bus device. |
Return Value |
This function returns -1 if there was a write collision else it returns a 0. |
Remarks: |
This function reads in a single byte from the I2C bus. This function performs the same function as MastergetcI2C. |
Function Prototype |
void NotAckI2C1(void); void NotAckI2C2(void); |
Include |
i2c.h |
Description |
Generates I2C bus Not Acknowledge condition. |
Arguments |
None |
Return Value |
None |
Remarks: |
This function generates an I2C bus Not Acknowledge condition. |
Function Prototype |
void OpenI2C1(unsigned int config1, unsigned int config2); void OpenI2C2(unsigned int config1, unsigned int config2); |
Include |
i2c.h |
Description |
Configures the I2C module |
Arguments |
config1 - This contains the parameter to configure the I2CCON register I2C Enable bit I2C_ON I2C_OFF I2C Stop in Idle Mode bit I2C_IDLE_STOP I2C_IDLE_CON SCL Release Control bit I2C_CLK_REL I2C_CLK_HLD Intelligent Peripheral Management Interface Enable bit I2C_IPMI_EN I2C_IPMI_DIS 10-bit Slave Address bit I2C_10BIT_ADD I2C_7BIT_ADD Disable Slew Rate Control bit I2C_SLW_DIS I2C_SLW_EN SMBus Input Level bits I2C_SM_EN I2C_SM_DIS General Call Enable bit I2C_GCALL_EN I2C_GCALL_DIS SCL Clock Stretch Enable bit I2C_STR_EN I2C_STR_DIS Acknowledge Data bit I2C_ACK I2C_NACK Acknowledge Sequence Enable bit I2C_ACK_EN I2C_ACK_DIS Receive Enable bit I2C_RCV_EN I2C_RCV_DIS Stop Condition Enable bit I2C_STOP_EN I2C_STOP_DIS Repeated Start Condition Enable bit I2C_RESTART_EN I2C_RESTART_DIS Start Condition Enable bit I2C_START_EN I2C_START_DIS
config2 - computed value for the baud rate generator |
Return Value |
None |
Remarks: |
This function configures the I2C Control register and I2C Baud Rate Generator register |
Function Prototype |
void RestartI2C1(void); void RestartI2C2(void); |
Include |
i2c.h |
Description |
Generates I2C Bus Restart condition. |
Arguments |
None |
Return Value |
None |
Remarks: |
This function generates an I2C Bus Restart condition. |
Function Prototype |
unsigned int SlavegetsI2C1(unsigned char *rdptr, unsigned int i2c_data_wait); unsigned int SlavegetsI2C2(unsigned char *rdptr, unsigned int i2c_data_wait); |
Include |
i2c.h |
Description |
This function reads pre-determined data string length from the I2C bus. |
Arguments |
rdptr - Character type pointer to RAM for storage of data read from I2C device. i2c_data_wait - This is the time-out count for which the module has to wait before return. If the time-out count is N, the actual time out would be about (20*N - 1) instruction cycles. |
Return Value |
Returns the number of bytes received from the I2C bus. |
Remarks: |
This routine reads a predefined data string from the I2C bus. |
Function Prototype |
unsigned int SlaveputsI2C1(unsigned char *wrptr); unsigned int SlaveputsI2C2(unsigned char *wrptr); |
Include |
i2c.h |
Description |
This function is used to write out a data string to the I2C bus. |
Arguments |
wrptr - Character type pointer to data objects in RAM. The data objects are written to the I2C device. |
Return Value |
This function returns 0 if the null character was reached in the data string. |
Remarks: |
This routine writes a data string out to the I2C bus until a null character is reached |
Function Prototype |
unsigned char SlaveReadI2C1(void); unsigned char SlaveReadI2C2(void); |
Include |
i2c.h |
Description |
This function is used to read a single byte from the I2C bus. |
Arguments |
None |
Return Value |
The return value is the data byte read from the I2C bus. |
Remarks: |
This function reads in a single byte from the I2C bus. This function performs the same function as SlavegetcI2C. |
Function Prototype |
void SlaveWriteI2C1(unsigned char data_out); void SlaveWriteI2C2(unsigned char data_out); |
Include |
i2c.h |
Description |
This function is used to write out a single byte to the I2C bus. |
Arguments |
data_out - A single data byte to be written to the I2C bus device. |
Return Value |
None |
Remarks: |
This function writes out a single data byte to the I2C bus device. This function performs the same function as SlaveputcI2C. |
Function Prototype |
void StartI2C1(void); void StartI2C2(void); |
Include |
i2c.h |
Description |
Generates I2C Bus Start condition. |
Arguments |
None |
Return Value |
None |
Remarks: |
This function generates an I2C Bus Start condition. |
Function Prototype |
void StopI2C1(void); void StopI2C2(void); |
Include |
i2c.h |
Description |
Generates I2C Bus Stop condition. |
Arguments |
None |
Return Value |
None |
Remarks: |
This function generates a I2C Bus Stop condition. |
Function Prototype |
void SlaveWaitForIntrI2C1(void); void SlaveWaitForIntrI2C2(void); |
Include |
i2c.h |
Description |
This routine will wait for Slave interrupt request and then clear interrupt Flag. |
Arguments |
None |
Return Value |
None |
Remarks: |
None |
Function Prototype |
void MasterWaitForIntrI2C1(void); void MasterWaitForIntrI2C2(void); |
Include |
i2c.h |
Description |
This routine will wait for Master interrupt request and then clear interrupt Flag. |
Arguments |
None |
Return Value |
None |
Remarks: |
None |
Include |
i2c.h |
Description |
This function is identical to SlaveReadI2C1 and SlaveReadI2C2, i.e., #define SlavegetcI2C1 SlaveReadI2C1 in i2c.h. |
Include |
i2c.h |
Description |
This function is identical to MastergetcI2C1 and MastergetcI2C2, i.e., #define MastergetcI2C1 MasterReadI2C1 in i2c.h. |
Macro |
EnableIntSI2C1 EnableIntIS2C2 |
Include |
i2c.h |
Description |
Macro enables I2C Slave Interrupt |
Arguments |
None |
Remarks |
None |
Macro |
DisableIntSI2C1 DisableIntIS2C2 |
Include |
i2c.h |
Description |
Macro disables I2C Slave Interrupt |
Arguments |
None |
Remarks |
None |
Macro |
EnableIntMI2C1 EnableIntIM2C2 |
Include |
i2c.h |
Description |
Macro enables I2C Master Interrupt |
Arguments |
None |
Remarks |
None |
Macro |
DisableIntMI2C1 DisableIntIM2C2 |
Include |
i2c.h |
Description |
Macro disables I2C Master Interrupt |
Arguments |
None |
Remarks |
None |
Macro |
SetPriorityIntSI2C1 SetPriorityIntSI2C2 |
Include |
i2c.h |
Description |
Macro sets the priority level for I2C Salve interrupt. |
Arguments |
priority - This input parameter is the level of interrupt priority. |
Remarks |
None |
Macro |
SetPriorityIntMI2C1 SetPriorityIntMI2C2 |
Include |
i2c.h |
Description |
Macro sets the priority level for I2C Master interrupt. |
Arguments |
priority - This input parameter is the level of interrupt priority. |
Remarks |
None |
Macro |
mI2C1_MasterClearIntr() mI2C2_MasterClearIntr() |
Include |
i2c.h |
Description |
This macro clears the I2C Master interrupt flag |
Arguments |
None |
Remarks |
None |
Macro |
mI2C1_SlaveClearIntr () mI2C2_SlaveClearIntr() |
Include |
i2c.h |
Description |
This macro clears the I2C Slave interrupt flag |
Arguments |
None |
Remarks |
None |